home *** CD-ROM | disk | FTP | other *** search
/ Shareware Super Platinum 8 / Shareware Super Platinum 8.iso / mac / PROGTOOL / DOCZ16.ZIP;1 / DOCZ.LIF / GETSTART.DOC < prev    next >
Encoding:
Text File  |  1994-04-24  |  4.9 KB  |  120 lines
  1.                   Getting Started With DOCZ Quickly!
  2.  
  3.  
  4. The Steps to Building a New DOCZ Documentation Library
  5.  
  6. (1)   DOCZ uses two directories located with environment variables to
  7.       find files:
  8.  
  9.          DOCSRC:  default source directory
  10.  
  11.          DOCREF:  reference file directory
  12.  
  13.       The installation procedure will have created a command file in 
  14.       the directory designated for executables:
  15.  
  16.          Unix:    docz_sym
  17.  
  18.          MSDOS:   DOCZ_SYM.BAT
  19.  
  20.          VMS:     SYS$MANAGER:DOCZ_LOGIN.COM
  21.  
  22.       This command file will create the required DOCSRC and DOCREF
  23.       environment symbols for use by DOCZ.  If you have not already, run
  24.       this command file so that DOCZ programs will be able to find the
  25.       files in the DOCSRC and DOCREF directories (the Unix command file
  26.       should be dot executed).
  27.  
  28. (2)   Select a name for your library.  The name may have, but does
  29.       not need to have a physical relationship to any object library or
  30.       group of programs.  The name should be up to 11 characters in length,
  31.       and should contain no punctuation.
  32.  
  33. (3)   Create a sub-directory to the DOCSRC directory (DOCSRC was
  34.       created during installation), with a name the same as the name you
  35.       have chosen for your library (upper case in Unix).
  36.  
  37. (4)   Select the modules to be contained in the documentation
  38.       library.  Modules are either subroutine names (when documenting
  39.       object libraries) or program names (when documenting program or
  40.       command file libraries).  They may also be object names when using an
  41.       object-oriented language.
  42.  
  43. (5)   Edit the Documentation Header in your source code for each
  44.       module you want to document.  Each source file may contain one or
  45.       many modules, and there will be one DOCZ Documentation Header for
  46.       each module in a source file.
  47.  
  48. (6)   Move the source files to your new DOCSRC subdirectory.
  49.  
  50. (7)   Run DOCXL or DOCLIS to add the module to the Documentation
  51.       Index (see the DOCXL or DOCLIS program reference).  DOCLIS will 
  52.       "mass-load" the documentation library with one invocation.  DOCXL will
  53.       add each module one at a time.
  54.  
  55. (8)   Run DOC on the library to test the documentation (see the DOC
  56.       program reference).
  57.  
  58. (9)   Run DOCHBLD to build an on-line help library (see the DOCHBLD
  59.       program reference).
  60.  
  61. (10)  Use the manual section, "SELECTING OPTIONS" to enhance and
  62.       modify your DOCZ environment.  If you are adapting DOCZ to a
  63.       pre-existing development environment, this manual section will show
  64.       you how to override the installation defaults used by DOCZ and set up
  65.       an environment more suitable to your current environment.  For
  66.       instance, your source code does not necessarily have to be stored in
  67.       a sub-directory with a name the same as the documentation library
  68.       name.
  69.  
  70. (11)  Use the manual section, "PUBLISHING DOCUMENTATION" to learn how
  71.       to automate Revision Notices and other types of DOCZ reports.
  72.  
  73.  
  74. The source files for many examples in various languages were
  75. deposited in the DOCSRC directory by the installation procedure.  In
  76. addition, the sample documentation library called CSUB may have been
  77. built from sample sources at DOCZ installation time, if that option
  78. was selected by the installer.  The bldocz command file has been
  79. provided in the DOCSRC directory to demonstrate how CSUB was built.
  80. Example Files in the DOCSRC directory.
  81.  
  82.    dochead.txt       generic prototype DOCZ header
  83.    dochelp.m         Brief macro for the DOCHELP utility
  84.    dochelp.txt       ASCII Transport File of DOCHBLD utility to
  85.                      build a help library for the DOCZ System
  86.    c.txt             Standard C Library on-line help transport file
  87.    fake.bas          BASIC source example
  88.    move.bat          MSDOS command file source example
  89.    cmdline.pas       Pascal source example
  90.    strmcpy.asm       8086 Assembly source example
  91.    strmcpy.mar       VAX11 Assembly source example
  92.    mailfile.com      VAX-DCL source example
  93.    strmcpy.c         C source example
  94.    cp_r.sh           Unix Bourne Shell source example
  95.    upcase.for        FORTRAN source example
  96.    macro.h           C macro example
  97.    gtsa.prg          Dbase example
  98.    frank.prl         Perl example
  99.    docstash          Unix SCCS Bourne Shell automation example
  100.    docstash.com      VMS CMS automation (DCL)
  101.    bldocz.bat        builds sample C function library (MSDOS)
  102.    bldocz            builds sample C function library (Unix)
  103.  
  104.  
  105. Example C Function Library
  106.  
  107. As an example for a real DOCZ application, a DOCZ reference manual
  108. containing six modules is contained in the file, CSUB.DOC.  The
  109. source files for the library are:
  110.  
  111.    delstr.asm
  112.    haspriv.c
  113.    insert.mar
  114.    juldate.c
  115.    macros.h
  116.    zero.c
  117.  
  118. This library happens to be a C function library, but the DOCZ System
  119. is not limited to any particular language.
  120.